=========================================================================
ISTRUZIONI per l'ASSEGNAMENTO DI RECUPERO INFORMATICA anno 2019/20
========================================================================
L'assegnamento prevede la realizzazione di alcune funzioni che effettuano mosse del gioco BUBBLE BREAKER.
Una descrizione piu' approfondita si trova nel file bbvs.pdf.

Cosa deve essere fatto:
(1) le funzioni il cui prototipo si trova nel file bbvs.h devono essere implementate in un file chiamato bbvs.c
(2) il file bbvs.c deve essere consegnato al docente nel formato "tar" creato automaticamente come descritto piu' sotto
(3) il "tar" deve essere allegato ad una normale mail da inviare al proprio docente (susanna.pelagatti@unipi.it per corsoA o conte@di.unipi.it per corsoB) con oggetto "info20: consegna secondo assegnamento"

------------------------------------------------
Estrarre il materiale dal KIT dell'assignment
------------------------------------------------
Creare una directory temporanea, copiare kit_ar.tar  
nella directory e spostarsi nella directory appena creata. Es.

$$ mkdir AssegnamentoR
$$ mv kit_ar.tar AssegnamentoR
$$ cd AssegnamentoR

S-tarare i file del kit con

$$ tar xvf kit_ar.tar

questo comando crea nella directory corrente una directory "BBVS"
con i seguenti file

$$ ls BBVS
bbvs.pdf    : file contenente la descrizione del gioco da realizzare

bbvs.h     : header file che contiene i prototipi delle funzioni da realizzare e definizioni

01test.c
02test.c
03test.c
04test.c    : file che contengono i main() di test forniti dai docenti (NON MODIFICARE)
        

Makefile    : un file che permette l'automatizzazione della compilazione e dei test forniti dai docenti (NON MODIFICARE)
      
README      : questo file


gruppo-check.pl   : uno script Perl che controlla il formato del file gruppo.txt prima di effettuare la consegna (NON MODIFICARE)

gruppo.txt    : un file di esempio di specifica del gruppo (massimo 2 studenti per gruppo)
        (deve essere aggiornato con i dati di chi consegna, secondo il formato esemplificato)

========================================================================
ISTRUZIONI per la realizzazione dell'assegnamento
========================================================================

L'assegnamento prevede la realizzazione di alcune funzioni
(le specifiche dettagliate si trovano nel file bbvs.pdf e nei commenti dei file bbvs.h).

Lo studente deve realizzare le funzioni secondo le specifiche, testandone via
via il funzionamento con delle funzioni main() sviluppate dallo studente in modo opportuno.

Quando si e' ragionevolmente sicuri della correttezza delle funzioni in base
alle specifiche ed ai test che abbiamo effettuato si puo' passare ai test
automatici contenuti nel Makefile e sviluppati dai docenti.
E' importante non eseguire i test del Makefile
con codice non precedentemente testato perche' in questo caso i risultati
sarebebro di difficile interpretazione e fuorvianti.

I test del Makefile sono 4:
1) il primo, attivabile dando da shell il comando
"make test1"
testa le funzioni per allocare, deallocare e riempire la board del gioco, e la funzione 'valida'.
Il test non fa altro che eseguire il main() contenuto nel file "01test.c" che lo studente e' invitato a leggere e comprendere.
2) il secondo test, attivabile dando da shell il comando
"make test2"
esegue uno 'stress test' eseguedo molte mosse su board diverse, verificando l'effetto sulla board, che vengano applicate le condizioni di gravita' avanzate, il punteggio ottenuto.
Il test non fa altro che eseguire il main() contenuto nel file "02test.c" che lo studente e' invitato a leggere e comprendere.
3) il terzo test (03test.c attivabile con "make test3") verifica la correttezza delle funzioni 'carica' e 'salva'
4) il quarto test (04test.c attivabile con "make test4") non fa altro che attivare il gioco complessivo attraverso la funzione 'gioca'.
Anche in questo caso invitiamo gli studenti a prendere visione e comprendere il main() in 04test.c che viene attivato da questo test.


------------------
Come procedere --> i passi :
-----------------

1) leggere attentamente bbvs.pdf

2) implementare e testare le funzioni in bbvs.h nel file bbvs.c

3) testare il software con i test forniti dai
  docenti. 

       $ make test1
       $ make test2
       $ make test3
       
       (e "$make test4" per provare a giocare)

  NOTA: (1) il file bbvs.c si deve trovare nella cartella BBVS/
 
  (2) E' importante che il test fornito dai docenti venga effettuato solo su
  un programma gia' funzionante e testato altrimenti i risultati
  possono essere di difficile interpretazione, fuorvianti o inutili.

4) preparare la documentazione: ovvero commentare adeguatamente il file bbvs.c
   ed inserire un'intestazione contenente i nomi
   degli sviluppatori ed  una dichiarazione di originalita' 

   /** \file bbvs.c
       \author Thomas Edison & Nikola Tesla
     Si dichiara che il contenuto di questo file e' in ogni sua parte opera
     originale degli  autori.  */


5) aggiornare il file "gruppo.txt" con i nomi e dati degli sviluppatori

6) consegnare il file eseguendo

      bash:~$ make consegna

   e seguendo le istruzioni.

   Il target consegna crea un file tar cognome.nome-corsoX-ar.tar
   Il file deve essere rinominato sostituendo "cognome" "nome" e "corso" con i propri dati (in caso di un gruppo, mettere i dati della persona che invia la mail) che deve essere inviato all'indirizzo del docente con oggetto:

   "info20: consegna assegnamento di recupero"

   Se il make non funziona nell'ambiente in cui state sviluppando, create
   un tar file con all'interno il file bbvs.c
   e gruppo.txt ed inviatelo al docente come sopra.
   Tutte le consegne verranno confermate con un messaggio entro 2/3
   giorni all'indirizzo da cui e' stata effettuata la consegna. In
   caso questo non si verifichi contattare il docente.
   

---------------------------------------
 NOTE IMPORTANTI: LEGGERE ATTENTAMENTE
---------------------------------------

1) tutti gli elaborati verranno confrontati fra di loro con tool automatici per stabilire eventuali situazioni di PLAGIO. Se gli elaborati sono ragionevolmente simili verranno scartati.

2) Chi in sede di orale risulta palesemente non essere l'autore del software consegnato in uno degli assegnamenti dovra' ripetere l'esame

3) Tutti i comportamenti scorretti ai punti 1 e 2 verranno segnalati ufficialmente al presidente del corso di laurea

----------------------------
 VALUTAZIONE DELL'ASSEGNAMENTO:
----------------------------

Il completamento dell'assegnamento è obbligatorio per poter sostenere l'esame.

La qualita' del codice consegnato e delle discussioni fornite valutata complessivamente da 0 a 30 e fara' media
con il voto dell'esame orale.
